FORMAT: 1A
HOST: https://api.jikan.moe/v3

# Jikan
[Jikan](https://jikan.moe) is an **Unofficial** MyAnimeList REST-ful API. 
It's built on the Lumen microframework, uses Redis for caching and is powered by the [Jikan PHP API](https://github.com/jikan-me/jikan)

Base URL: `https://api.jikan.moe/v3`

[Bug Report](https://github.com/jikan-me/jikan/issues/new) | **[Discord](https://discordapp.com/invite/4tvCr36)**

## Announcement - 29 December, 18
REST v3.2 has been released!

#### New Features
- Anime/Manga **Reviews**
- Anime/Manga **Recommendations**
- Anime/Manga **User Updates**
- [Club **Information**](https://jikan.docs.apiary.io/#reference/0/club)
- [Club **Members**](https://jikan.docs.apiary.io/#reference/0/club)
- [Season **later**](https://jikan.docs.apiary.io/#reference/0/season-later)
- [Entity Tags - Cache validation](https://jikan.docs.apiary.io/#introduction/cache-validation)

**Important Changes**
- All data from user related endpoints `/v3/user/*` are now cached for 5 minutes only
- **(Anime/Manga)** Bug fixed for `related` property. It's an object but returns an array when it was empty. **This is fixed now.**



## Links
- [Website](https://jikan.moe)
- [About](https://jikan.moe/about)
- [Projects/Apps using Jikan](https://jikan.moe/showcase)
- [REST API Status](https://status.jikan.moe)


## Wrappers
- [JikanPHP - Parser](https://github.com/jikan-me/jikan/) by [Contributors](https://github.com/jikan-me/jikan/graphs/contributors)
- [JikanPy - Wrapper](https://github.com/AWConant/jikanpy) by Andrew Conant & abhinavk99 (Abhinav Kasamsetty)
- [Jikan.rb - Wrapper](https://github.com/Zerocchi/jikan.rb) by Zerocchi
- [Jikan.Net - Wrapper](https://github.com/Ervie/jikan.net) by Ervie (Bartłomiej Buchała)
- [JikanJs - Wrapper](https://github.com/zuritor/jikanjs) by zuritor (Sven)
- [Jikan4java - Wrapper](https://github.com/Doomsdayrs/Jikan4java) by Doomsdayrs
- [Jikan-php - Wrapper](https://github.com/janvernieuwe/jikan-jikanPHP) by Jan Vernieuwe
- [Jikan-node - Wrapper](https://github.com/xy137/jikan-node) by xy137

# Information

## Rate Limiting
Daily Limit: **Unlimited**

- **30 requests** / minute
- **2 requests** / second

**Note: Cached requests are NOT throttled**

### Bulk Requests
This API serves as a purpose for apps/bots/etc that make consistent amount of requests. **If you're using the API for making bulk requests, keep a 3 second delay between each request. Abuse of the API will result in an IP ban.**

## Response Schema Notes
- Any property (except arrays) whose value does not exist or is undertermined, will be `null`
- Any array property whose value does not exist or is undetermined, will be **empty**
- Any `score` property whose value does not exist or is undetermined, will be `0`
- All dates and timestamps are in **ISO8601** format and in **UTC**

## Caching
User related requests are cached for **5 minutes**

All other requests are cached for **6 hours**

- `request_cached` (bool) will tell you whether the request is cached

- `request_cache_expiry` is the cache TTL in seconds

## Allowed HTTP(s) requests
<pre>
GET: All requests are done via GET
</pre>

# Response Headers
- 200 `OK` - the request was successful.
- 304 `Not Modified` - You have the latest data
- 400 `Bad Request` - You've made an invalid request or to an invalid endpoint.
- 404 `Not Found` - MyAnimeList responded with a 404
- 405 `Method Not Allowed` - requested method is not supported for resource.
- 429 `Too Many Requests` - You are being rate limited or Jikan is being rate-limited by MyAnimeList

# Errors
If you get an error response, it'll be within the `error` field. Here's an example:
```
{"error": "Something Happened"}
```

Here's a list of errors you can get and what you could do to over come them. Appropriate status headers are sent.

### Invalid extended request / Unsupported parse request
Check each method for their proper extended requests. For example `/episodes` may exist for anime, but it doesn't exist for manga.

### Invalid or incomplete endpoint
The endpoint you requested either does not exist or you did not make a proper request.

### Bad Request
Same as above

### Other errors
If there's any 404s or the parser is unable to complete the request, you'll get the appropriate status and header for that error.


# Disclaimer
- Jikan is not affiliated with MyAnimeList.
- Jikan is a **free**, open-source API. Use it responsibly.
- **Any abuse of the REST API instance will lead to temporary IP blocks!**


# Cache Validation
- All requests return a `ETag` header which is an md5 hash of the content.

- You can use this hash to verify if there's new or updated content by supplying it as the value for the `If-None-Match` header.

- You will get a `304` HTTP response if your value and the data on Jikan matches.

- If there's new/updated content, you'll get a normal `200` HTTP response with the updated content.

### How To Use
1. Use the `ETag` value as a header value for `If-None-Match` for future requests
2. If the content has changed, you will get a `304 - Not Modified` header response, otherwise `200 - OK`


![Cache Validation](https://i.imgur.com/925ozVn.png "Cache Validation")


## Anime [/anime/{id}/{request}/{parameter}]
A single anime object with all its details
### Requests
| Request  | Parameter | Description |
| ------------- | ------------- | ------------- |
| characters_staff  | N/A  | Fetches the list of characters & staff members of the anime |
| episodes  | Page number (integer)  | Fetches the list of episodes of the anime |
| news | N/A | News related to the item |
| pictures | N/A | Pictures related to the item |
| videos | N/A | PV & episodes (if any) related to the item |
| stats | N/A | Statistical information related to the item |
| forum | N/A | Forum topics related to the item |
| moreinfo | N/A | More info related to the item |
| reviews | Page number (integer) | Reviews written by users |
| recommendations | N/A | Recommendations and their weightage made by users |
| userupdates | Page number (integer) | Latest list updates made by users |



#### Remarks 
- The field `episodes_last_page` will tell you the last page of the paginated episodes list.

- The episodes page on MyAnimeList get paginated after 100 episodes. If there's an anime with more than 100 episodes, you'll have to use the parameter.

- Only 20 items are shown per page for reviews

### Example Calls
- `/anime/1/characters_staff` // Returns the list of characters and staff
- `/anime/1/episodes` // Defaults to the 1st page
- `/anime/1/episodes/1` // Same as above
- `/anime/1/episodes/2` // Returns 2nd page if there's any


### Anime Request Example+Schema [GET]

+ Parameters
    + id (required, Number, `1`) ... Returns the Anime details from that the ID
    + request (optional, String, `episodes`) ... More details such as characters, staff, episodes
    + parameter (optional, Number, `2`) ... Anime with more than 100 episodes are paginated, hence this parameter is required.

+ Response 200 (application/json)

        [
 
        ]
        

## Manga [/manga/{id}/{request}]
A single manga object with all its details
### Requests
| Request  | Parameter | Description |
| ------------- | ------------- | ------------- |
| characters  | N/A  | Fetches the list of characters & staff members of the manga |
| news | N/A | News related to the item |
| pictures | N/A | Pictures related to the item |
| stats | N/A | Statistical information related to the item |
| forum | N/A | Forum topics related to the item |
| moreinfo | N/A | More info related to the item |
| reviews | Page number (integer) | Reviews written by users |
| recommendations | N/A | Recommendations and their weightage made by users |
| userupdates | Page number (integer) | Latest list updates made by users |

### Example Calls
- `/manga/1/characters` // Returns the list of characters and staff


#### Remarks 

- Only 20 items are shown per page for reviews

### Manga Request Example+Schema [GET]

+ Parameters
    + id (required, Number, `1`) ... Returns the Character details from that the ID
    + request (optional, String, `characters`) ... More details such as characters
    
+ Response 200 (application/json)

        [
 
        ]
        
## Person [/person/{id}/{request}]
A single person object with all its details
### Requests
| Request  | Parameter | Description |
| ------------- | ------------- | ------------- |
| pictures | N/A | Pictures related to the item |

### Person Request Example+Schema [GET]

+ Parameters
    + id (required, Number, `1`) ... Returns the Person details from that the ID
    + request (optional, String, `pictures`) ... Pictures related to the item

+ Response 200 (application/json)

        [
 
        ]
        
## Character [/character/{id}/{request}]
A single character object with all its details
### Requests
| Request  | Parameter | Description |
| ------------- | ------------- | ------------- |
| pictures | N/A | Pictures related to the item |

### Character Request Example+Schema [GET]


+ Parameters
    + id (required, Number, `1`) ... Returns the Character details from that the ID
    + request (optional, String, `pictures`) ... Pictures related to the item
   
+ Response 200 (application/json)

        [
 
        ]
        
        
## Search [/search/{type}/?q=Fate/Zero&page=1]
Search results for the query

**NOTE: MyAnimeList only processes queries with a minimum of 3 letters**
### Parameters
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| type | anime, manga, person, character | Specify where to search |
| query **(v2 only)** | STRING | Query you want to search |
| page | INTEGER | Page number of the results |

### Advanced Search Parameters (Anime & Manga)
**Note:** These are search filters which have to be passed as GET `key=value`
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| q **(required for v3+)** | STRING | For UTF8 characters, percentage encoded and queries including back slashes |
| page | INTEGER | Page number |
| type | `tv` `ova` `movie` `special` `ona` `music` `manga` `novel` `oneshot` `doujin` `manhwa` `manhua` | Filter type of results |
| status | `airing` `completed` `complete` (alias) `tba` `upcoming` (alias) | Filter status of results |
| rated | `g` `pg` `pg13` `r17` `r` `rx` | Filter age rating of results - [View Meaning](https://jikan.moe/docs#advanced-search-rating-constants) |
| genre | INTEGER : 1-43 | These values reflect the genre IDs of MyAnimeList - [View Values](https://jikan.moe/docs#advanced-search-genre-constants) |
| score | FLOAT : 0.0-10.0 | Filter score of results |
| start_date | ISO8601 | Filter start date of results |
| end_date | ISO8601 | Filter end date of results |
| genre_exclude | boolean : 0/1 | To exlude/include the `genre` you added in your request |

### Search Filters
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| limit | INTEGER | Limits item results to the amount specified |

#### Examples
`/search/manga/Grand%20Blue/1` **(DEPRECIATED v3+)**

`/search/manga?q=Grand%20Blue&page=1` **(RECOMMENDED)**

The first way won't work due to the back slash in "Fate/Zero". It's encouraged to use the the GET method below for all queries since it responds more accurately for UTF8 characters and percentage encoding.

`/search/anime?q=Fate/Zero&page=1`

Furthermore, the former method is **depreciated** in v3+. Use `q` for passing queries.

`/search/people/?q=Sawashiro&limit=3`

### Search Request Example+Schema [GET]


+ Parameters
    + type (required, String, `anime`) ... Returns result from anime search
   
+ Response 200 (application/json)

        [
 
        ]
        

## Season [/season/{year}/{season}]
Anime of the specified season

**Note:** Both parameters are required.
### Parameters
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| year | Integer: Year | Specify the year |
| season | `summer` `spring` `fall` `winter` | Specify the season |

### Season Request Example+Schema [GET]

+ Parameters
    + year (required, Integer, `2018`) ... Returns anime of the year
    + season (required, String, `winter`) ... Returns anime of the season

+ Response 200 (application/json)

        [
 
        ]
        
## Season Archive [/season/archive]
All the years & their respective seasons that can be parsed from MyAnimeList

### Season Archive Request Example+Schema [GET]

+ Response 200 (application/json)

        [
 
        ]
        

## Season Later [/season/later]
Anime that have been announced for the upcoming seasons

### Season Later Request Example+Schema [GET]

+ Response 200 (application/json)

        [
 
        ]
        
## Schedule [/schedule/{day}]
Anime schedule of the week or specified day

**Note:** If you don't pass the `day` parameter, it'll return the schedule for **all** days of the week
### Parameters
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| day (optional) | `monday` `tuesday` `wednesday` `thursday` `friday` `saturday` `sunday`, `other` **(v3)**, `unknown` **(v3)** | Anime scheduled for that specific day |

### Schedule Request Example+Schema [GET]

+ Parameters
    + day (optional, String, `monday`) ... Returns scheduled anime of that specific day
    
+ Response 200 (application/json)

        [
 
        ]
        
## Top [/top/{type}/{page}/{subtype}]
Top items on MyAnimeList

**Note:** `subtype` returns a filtered top list of a type `type` item. For example, the top Anime (type) movies (subtype)
**Note 2:** `subtype` is only for `anime` and `manga` types.
**Note 3:** Date properties are returned in string as they only consist of the month and year - which is not appropriate for ISO8601

### Parameters
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| type | `anime` `manga`, `people` (v3+), `characters` (v3+) | Top items of this type |
| page (optional) | INTEGER | The Top page on MyAnimeList is paginated offers 50 items per page |
| subtype (optional) | **Anime:** `airing` `upcoming` `tv` `movie` `ova` `special` **Manga:** `manga` `novels` `oneshots` `doujin` `manhwa` `manhua` **Both:** `bypopularity` `favorite` |

### Top Request Example+Schema [GET]

+ Parameters
    + type (required, String, `anime`) ... Returns top items of this type
    + page (optional, Integer, `1`) ... Pagination support
    + subtype (optional, String, `upcoming`) ... Returns top items of this type filtered by their subtypes
    
+ Response 200 (application/json)

        [
 
        ]
        
## Genre [/genre/{type}/{genre_id}/{page}]
Anime/Manga items of the genre

**Note:** Genres with their respective IDs are listed [here]()
### Parameters
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| type | `anime` `manga` | Genre of this type |
| genre_id | INTEGER | Genre ID from MyAnimeList - [Genre Mapping]() |
| page (optional) | |

### Genre Request Example+Schema [GET]

+ Parameters
    + type (required, String, `anime`) ... Returns anime/manga items of this genre
    + genre_id (optional, Integer, `1`) ... Genre ID
    + page (optional, Integer, `1`) ... Pagination
    
+ Response 200 (application/json)

        [
 
        ]
        
## Producer [/producer/{producer_id}/{page}]
Anime by this Producer/Studio/Licensor

### Parameters
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| producer_id | INTEGER | Producer ID from MyAnimeList |
| page (optional) | |

### Producer Request Example+Schema [GET]

+ Parameters
    + producer_id (optional, Integer, `1`) ... Producer ID
    + page (optional, Integer, `1`) ... Pagination
    
+ Response 200 (application/json)

        [
 
        ]
        
## Magazine [/producer/{magazine_id}/{page}]
Manga by this Magazine/Serializer/Publisher

### Parameters
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| magazine_id | INTEGER | Magazine ID from MyAnimeList |
| page (optional) | |

### Magazine Request Example+Schema [GET]

+ Parameters
    + magazine_id (optional, Integer, `1`) ... Magazine ID
    + page (optional, Integer, `1`) ... Pagination
    
+ Response 200 (application/json)

        [
 
        ]
        
## User [/user/{username}/{request}/{argument}]
User related data

**Note:** About is returned in HTML as MyAnimeList allows custom "about" sections for users that can consist of images, formatting, etc.

**Note 2:** Anime & Manga Lists are paginated. Only 300 items are returned per page.

### Parameters
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| username | string | Username on MyAnimeList |
| request | `profile`, `history`, `friends`, `animelist`, `mangalist` |
| data (optional) | Additional data for the requests |

#### Data
| Data  | Argument | Description |
| ------------- | ------------- | ------------- |
| history | `anime`, `manga` | Returns both combined if neither are passed |
| friends | INTEGER | Pagination support; Status 404 if there's no friends on the page |
| animelist | `all`, `watching`, `completed`, `onhold`, `dropped`, `plantowatch`, `ptw` (alias) |
| mangalist | `all`, `reading`, `completed`, `onhold`, `dropped`, `plantoread`, `ptr` (alias) |

#### Examples
`/user/nekomata1037` - Parses Profile

`/user/nekomata1037/profile` (alias)

`/user/nekomata1037/history` - Parses user history (anime+manga)

`/user/nekomata1037/history/anime` - Parses user history (anime only)

`/user/nekomata1037/friends` - Parses user friends

The request below will return 404 because I don't have that many friends on MAL to generate a second page.
`/user/nekomata1037/friends/2` - Parses user friends (from page 2)


**Anime & Manga Lists**

Lists are paginated (300 items per page).

`/user/nekomata1037/animelist/all` - All anime in user list

`/user/nekomata1037/animelist/all/2` - Page 2

`/user/nekomata1037/mangalist/reading` - Manga that I'm currently reading

### User Request Example+Schema [GET]
+ Parameters
    + username (required, string, `Nekomata1037`) ... Username on MyAnimeList
    + request (optional, string, `history`) ... Request
    + argument (optional, string, `anime`) ... Request argument

+ Response 200 (application/json)

        [
 
        ]


## Club [/club/{id}/{request}]
A single club object with all its details
### Requests
| Request  | Parameter | Description |
| ------------- | ------------- | ------------- |
| members  | Page (INTEGER)  | Fetches list of club members |


### Example Calls
- `/club/1` // Returns club information
- `/club/1/members/1` // Returns list of club members


#### Remarks 

- Only 35 items are shown per page for members

### Club Request Example+Schema [GET]

+ Parameters
    + id (required, Number, `1`) ... Returns the Club details from that the ID
    + request (optional, String, `members`) ... Return club members
    
+ Response 200 (application/json)

        [
 
        ]


## Meta [/meta/{request}/{type}/{period}]
Requests related to meta information regarding the Jikan REST Instance.
Such as the most requested endpoints for a specific period, or just status on the REST API.

### Parameters
| Parameter  | Argument | Description |
| ------------- | ------------- | ------------- |
| request | `requests` `status` | |
| type | `anime` `manga` `character` `person` `search` `top` `schedule` `season`  | This is only for the `requests` endpoint |
| period  | `today` `weekly` `monthly` | This is only for the `requests` endpoint |
| offset | int | 1,000 requests are shown per page, you can use the offset to show more |

### Meta Request Example+Schema [GET]

+ Parameters
    + request (required, String, `requests`) ... 
    + type (required, String, `anime`) ... 
    + period (required, String, `today`) ... 

+ Response 200 (application/json)

        [
 
        ]